package com.apikey.auth.service;

import com.apikey.auth.entity.ApiKey;
import com.apikey.auth.entity.History;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;

import java.time.LocalDateTime;
import java.util.List;
import java.util.Map;

/**
 * 历史记录服务接口
 * 提供API Key历史记录的管理和查询功能
 *
 * @author API Key Framework
 * @version 1.0
 */
public interface HistoryService {

    /**
     * 记录API Key变更历史
     *
     * @param apiKey        API Key信息
     * @param operationType 操作类型
     * @param operatorId    操作者ID
     */
    void recordHistory(ApiKey apiKey, String operationType, String operatorId);

    /**
     * 记录API Key变更历史（带变更原因）
     *
     * @param apiKey        API Key信息
     * @param operationType 操作类型
     * @param operatorId    操作者ID
     * @param changeReason  变更原因
     */
    void recordChange(ApiKey apiKey, String operationType, String operatorId, String changeReason);

    /**
     * 记录API Key更新历史
     *
     * @param apiKey     API Key信息
     * @param operatorId 操作者ID
     */
    void recordUpdate(ApiKey apiKey, String operatorId);

    /**
     * 分页查询历史记录
     *
     * @param userId        用户ID
     * @param operatorId    操作者ID
     * @param operationType 操作类型
     * @param apiKeyValue   API Key值
     * @param startTime     开始时间
     * @param endTime       结束时间
     * @param pageable      分页参数
     * @return 分页结果
     */
    Page<ApiKey> findHistoryRecords(String userId, String operatorId, String operationType,
                                    String apiKeyValue, LocalDateTime startTime, LocalDateTime endTime,
                                    Pageable pageable);

    /**
     * 根据ID查找历史记录
     *
     * @param id 历史记录ID
     * @return 历史记录
     */
    ApiKey findHistoryById(Long id);

    /**
     * 比较两个历史记录的差异
     *
     * @param id1 第一个历史记录ID
     * @param id2 第二个历史记录ID
     * @return 差异信息
     */
    Map<String, Object> compareHistoryRecords(Long id1, Long id2);

    /**
     * 从历史记录恢复API Key
     *
     * @param historyId 历史记录ID
     * @return 恢复的API Key
     */
    ApiKey restoreFromHistory(Long historyId);

    /**
     * 获取总历史记录数
     *
     * @param startTime 开始时间
     * @param endTime   结束时间
     * @return 总记录数
     */
    long getTotalHistoryCount(LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 获取指定操作类型的记录数
     *
     * @param operationType 操作类型
     * @param startTime     开始时间
     * @param endTime       结束时间
     * @return 记录数
     */
    long getOperationCount(String operationType, LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 获取操作类型分布
     *
     * @param startTime 开始时间
     * @param endTime   结束时间
     * @return 操作类型分布
     */
    Map<String, Object> getOperationDistribution(LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 获取每日操作统计
     *
     * @param startTime 开始时间
     * @param endTime   结束时间
     * @return 每日操作统计
     */
    List<Map<String, Object>> getDailyOperationStats(LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 清理旧的历史记录
     *
     * @param days 保留天数
     * @return 删除的记录数
     */
    int cleanupOldHistory(int days);

    /**
     * 清理旧的历史记录
     *
     * @param beforeDate 删除此日期之前的记录
     * @return 删除的记录数
     */
    int cleanupOldHistory(LocalDateTime beforeDate);


    /**
     * 多条件分页查询历史记录
     *
     * @param apiKeyId      API Key ID过滤
     * @param operatorId    操作者ID过滤
     * @param operationType 操作类型过滤
     * @param startTime     开始时间
     * @param endTime       结束时间
     * @param pageable      分页参数
     * @return 历史记录分页结果
     */
    Page<History> getHistory(Long apiKeyId, String operatorId, String operationType,
                             LocalDateTime startTime, LocalDateTime endTime, Pageable pageable);

    /**
     * 搜索历史记录
     *
     * @param keyword 关键字
     * @param page    页码
     * @param size    每页大小
     * @return 历史记录分页结果
     */
    Page<History> searchHistory(String keyword, int page, int size);

    /**
     * 获取总操作次数
     *
     * @return 总操作次数
     */
    long getTotalOperationCount();

    /**
     * 获取今日操作次数
     *
     * @return 今日操作次数
     */
    long getTodayOperationCount();

    /**
     * 获取顶级操作者列表
     *
     * @param limit 限制数量
     * @return 顶级操作者列表
     */
    List<Map<String, Object>> getTopOperators(int limit);

    /**
     * 获取API Key变更趋势
     *
     * @param days 统计天数
     * @return 变更趋势数据
     */
    List<Map<String, Object>> getChangeTrend(int days);

    /**
     * 导出历史记录
     *
     * @param format        导出格式
     * @param apiKeyId      API Key ID
     * @param operatorId    操作者ID
     * @param operationType 操作类型
     * @param startTime     开始时间
     * @param endTime       结束时间
     * @return 导出数据
     */
    String exportHistory(String format, Long apiKeyId, String operatorId, String operationType,
                         LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 根据ID查找历史记录
     *
     * @param id 历史记录ID
     * @return 历史记录
     */
    History findById(Long id);

    /**
     * 比较两个历史记录
     *
     * @param id1 历史记录ID1
     * @param id2 历史记录ID2
     * @return 比较结果
     */
    Map<String, Object> compareHistory(Long id1, Long id2);

    /**
     * 查找历史记录
     *
     * @param apiKeyId   API Key ID (可为null)
     * @param operatorId 操作者ID
     * @param operation  操作类型
     * @param startTime  开始时间
     * @param endTime    结束时间
     * @param pageable   分页参数
     * @return 历史记录分页结果
     */
    Page<History> findHistory(Long apiKeyId, String operatorId, String operation,
                              LocalDateTime startTime, LocalDateTime endTime, Pageable pageable);

    /**
     * 获取操作类型统计信息
     *
     * @return 操作类型统计列表
     */
    List<Map<String, Object>> getOperationTypeStats();
}